{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "import sisl"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    }
   },
   "source": [
    "#### sisl + TBtrans + TranSiesta\n",
    "\n",
    "Welcome to the tutorial on the tools:\n",
    "\n",
    "- sisl (>=0.15.0)\n",
    "- TBtrans (>=5.0.0)\n",
    "- Siesta (>=5.0.0) (TranSiesta is part of the Siesta binary)\n",
    "\n",
    "Throughout this tutorial, you will work with the Jupyter notebook scheme.  \n",
    "A few rules about the notebook format is:\n",
    "\n",
    "- Everything in the notebook is parsed as Python code. One can do *any* Python code in here. So feel free to explore.\n",
    "- If things crash, then select (at the top) `Kernel -> Restart Kernel and Run All Cells...` to restart the kernel and then rerun all cells.\n",
    "- Press `h` for a quick help menu. These below commands are useful:\n",
    "  - `Esc` escape from editing the current cell\n",
    "  - `y` changes the current cell to a code-field, Python code\n",
    "  - `m` changes the current cell to a text-field, Markdown with (limited) $\\LaTeX$ support\n",
    "  - `Enter` edit current marked cell\n",
    "  - `Shift + Enter` execute current cell and skip to next cell\n",
    "  - `Alt + Enter` execute current cell and insert new cell below\n",
    "\n",
    "The tutorials encourage you to _explore_ the possibilities of extracting quantities using `sisl`. You are thus encouraged to read about relevant functions and methods to explore intrinsic capabilities.\n",
    "\n",
    "One can always get help regarding any class, function or method by invoking:\n",
    "\n",
    "    help(<>)\n",
    "    \n",
    "For instance to get help regarding a specific function in a class, you may invoke either of the following 2 lines of code, whichever you prefer (the first will divide the current window with this and a help window, while the other will print out):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "%pdoc sisl.Geometry.tile\n",
    "help(sisl.Geometry.tile)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If in doubt of arguments to routines it may help you greatly to remember the above functionality.\n",
    "Alternatively you can find the `sisl` API documentation [here](https://zerothi.github.io/sisl/api/index.html). You will be asked to search this API documentation throughout the workshop, it may help to have it open at all times."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    "# Tutorials\n",
    "\n",
    "This tutorial is made up in consecutive examples such that one is first, introduced to the transport methodology using TBtrans. So called “tight-binding” Hamiltonians are excellent examples to understand the methodology. They are extremely simple and may be used to shed light on more complicated issues.  \n",
    "Subsequent to the understanding of sisl and TBtrans, the tutorial will show how to analyze generic output from the DFT, Siesta. In particular the calculation of band-structures, DOS and plotting real-space quantities.  \n",
    "Lastly, the tutorial presents examples of self-consistent bias calculations using TranSiesta. These are merely extensions of the same simplistic modelling used in the tight-binding calculation and we try and retrieve the same results as using sisl and TBtrans. If your interest lie only with TranSiesta, do not be tempted to skip the tight-binding, nor Siesta, exercises. By understanding the underlying methodology for simple transport problems it becomes much easier to extrapolate to more complex/larger systems!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    "All tutorials are hosted online [here (version 2023)](https://github.com/zerothi/ts-tbt-sisl-tutorial/tree/2023)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Table of contents"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    "The tutorials may be found in sub-folders (or by pressing the links):\n",
    "\n",
    "### Tight-binding\n",
    "\n",
    "Tight-binding examples are extremely important in understanding basic principles of complex systems.\n",
    "\n",
    "- [TB 1](TB_01/run.ipynb)  \n",
    "  A basic example of how to create electronic structures in `sisl`.  \n",
    "  The graphene electronic structure is recreated from a simple tight-binding calculation.\n",
    "  In this example you will get your first glance at `sisl` code and how to utilize it for simple things.\n",
    "  \n",
    "- [TB 2](TB_02/run.ipynb)  \n",
    "  Creation of your first tight-binding Hamiltonian for TBtrans.\n",
    "  This, again, creates a graphene device with 2 electrodes and a small scattering region.\n",
    "  After having created the electronic structure to be fed into TBtrans you will run TBtrans. Then returning to the tutorial script you will run some data-analysis using `sisl` again.\n",
    "\n",
    "- [TB 3](TB_03/run.ipynb)  \n",
    "  Create transport in a skewed lattice. This exemplifies the generality of TBtrans, but also TranSiesta for cases where skewed transport directions reduces the computational effort.\n",
    "  \n",
    "  *Fast example*\n",
    "  \n",
    "- [TB 4](TB_04/run.ipynb)  \n",
    "  Introduction to the `sisl.io` module which interfaces the build-in file types. In this case we concentrate on the TBtrans output file `*.TBT.nc` where `sisl` is the primary tool to perform data-analysis. Extraction of transmission, DOS, spectral DOS and the aforementioned quantities on individiual subsets of atoms.\n",
    "  \n",
    "- [TB 5](TB_05/run.ipynb)  \n",
    "  Same system as in [TB 4](TB_04/run.ipynb). This example shows you the importance of utilising the periodicity in the electrodes. The exercises elaborates on [TB 4](TB_04/run.ipynb) and will teach you to extract transmission and density of states quantities on a *per $\\mathbf k$-point* case, thus enabling investigations at a Brillouin zone level.\n",
    "\n",
    "- [TB 6](TB_06/run.ipynb)  \n",
    "  The first $N>2$-electrode example with a cross-bar graphene nano-ribbon system. You will learn to extract data from a calculation with multiple electrodes and also explore details of symmetry for $N>2$ electrode systems.\n",
    "\n",
    "- [TB 7](TB_07/run.ipynb)  \n",
    "  Advanced exercise of *manipulation* of a predefined Hamiltonian. This example will cover how to add a magnetic field to a tight-binding Hamiltonian. This may be accomblished by using the $\\delta\\mathbf H$/$\\delta\\boldsymbol\\Sigma$ method.\n",
    "  \n",
    "- [TB 8](TB_08/run.ipynb)  \n",
    "  Advanced exercise for creating *real space self-energies*. This example will cover how to remove $\\mathbf k$-point sampling using real space methods.\n",
    "\n",
    "- [TB 9](TB_09/run.ipynb)  \n",
    "  Exercise in *bound-states* in NEGF methods. Here you will learn how to find and fine-tune the options for calculating bound-state properties.\n",
    "\n",
    "<!--\n",
    "Create a new tutorial which emphasizes the potential block.\n",
    "I.e. create a *fake* potential drop between the electrodes, say a Fermi-function.\n",
    "Then let the students play with the electrode position and buffer atoms.\n",
    "-->\n",
    "\n",
    "### Siesta\n",
    "\n",
    "Siesta has many utilities to post-process output such as, calculating DOS from the eigenspectrum, analyzing real-space charge and plotting molecular orbitals/wavefunctions (for experienced Siesta users `denchar` should be a familiar name). These tutorials shows how to use `sisl` to do the same analysis. It may be useful to read [this page](https://zerothi.github.io/sisl/api/io/siesta.html) which contains the current list of files that `sisl` may interact with.\n",
    "\n",
    "- [S 1](S_01/run.ipynb)  \n",
    "  A first hands-on using `sisl` to read in the electronic structure from DFT output.\n",
    "- [S 2](S_02/run.ipynb)  \n",
    "  Analyze density of states output from Siesta.\n",
    "- [S 3](S_03/run.ipynb)  \n",
    "  Plotting real-space quantities (wave-functions, densities etc.)\n",
    "  \n",
    "  \n",
    "### TranSiesta\n",
    "- [TS 1](TS_01/run.ipynb)  \n",
    "  The first TranSiesta example. Simple graphene TranSiesta calculation where you will learn about the importance of principle cell connections *only*.\n",
    "  \n",
    "- [TS 2](TS_02/run.ipynb)  \n",
    "  The first TranSiesta example with applied bias. You will learn to perform effective bias calculations and also to interpolate Hamiltonians for accurate $I(V)$ curves with a minimal/few self-consistently calculated Hamiltonians.\n",
    "\n",
    "- [TS 3](TS_03/run.ipynb)  \n",
    "  Learn how to create your first input for TranSiesta, from scratch.  \n",
    "  Create a 1D Carbon chain model with proper electrodes, a minimal scattering region and inputs for both TranSiesta and TBtrans.\n",
    "  \n",
    "- [TS 4](TS_04/run.ipynb)  \n",
    "  A multi-electrode calculation with TranSiesta. Two overlying Carbon chains in a cross-bar configuration. In this tutorial you are encouraged to play around with data-extraction utilities such as orbital-resolved DOS, etc.\n",
    "  \n",
    "- [TS 5](TS_05/run.ipynb)  \n",
    "  Advanced example by using buffer atoms in a TranSiesta calculation. Buffer atoms are equivalent to *removing* the atoms in the TranSiesta calculation. They are however necessary when performing calculations using non equivalent electrodes and/or different periodicities."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In addition to the above examples there are a few *advanced* examples where you are challenged by the capabilities of TBtrans and TranSiesta.\n",
    "\n",
    "### Advanced examples\n",
    "\n",
    "Here is an assorted list of advanced examples.  \n",
    "They are not intended to be carried out in any particular order. So read the initial description and try the examples that you find most interesting.\n",
    "\n",
    "- [Advanced 1](A_01/run.ipynb)  \n",
    "  Use buffer atoms instead of changing the input Hamiltonian\n",
    "  \n",
    "- [Advanced 2](A_02/run.ipynb)  \n",
    "  The advanced contour input of TranSiesta allows a variety of contours. Here you will try and create different contours and use some of the advanced contour methods.\n",
    "  \n",
    "- [Advanced 3](A_03/run.ipynb)  \n",
    "  Create a 4 (or 6) terminal Hall-bar configuration using tight-binding.\n",
    "  \n",
    "- [Advanced 4](A_04/run.ipynb)  \n",
    "  Create a 3rd nearest neighbour graphene model.\n",
    " \n",
    "- [Advanced 5](A_05/run.ipynb)  \n",
    "  Create a chain connecting to a C$_{60}$ molecule and perform molecular transmission projections.\n",
    "\n",
    "- [Advanced 6](A_06/run.ipynb)  \n",
    "  Explore the effect of convergence by improving the initial Hamiltonian by long and short potential relaxation regions towards the electrodes in the device."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
